home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nss / secmime.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  8KB  |  196 lines
  1. /* ***** BEGIN LICENSE BLOCK *****
  2.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3.  *
  4.  * The contents of this file are subject to the Mozilla Public License Version
  5.  * 1.1 (the "License"); you may not use this file except in compliance with
  6.  * the License. You may obtain a copy of the License at
  7.  * http://www.mozilla.org/MPL/
  8.  *
  9.  * Software distributed under the License is distributed on an "AS IS" basis,
  10.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11.  * for the specific language governing rights and limitations under the
  12.  * License.
  13.  *
  14.  * The Original Code is the Netscape security libraries.
  15.  *
  16.  * The Initial Developer of the Original Code is
  17.  * Netscape Communications Corporation.
  18.  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19.  * the Initial Developer. All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *
  23.  * Alternatively, the contents of this file may be used under the terms of
  24.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26.  * in which case the provisions of the GPL or the LGPL are applicable instead
  27.  * of those above. If you wish to allow use of your version of this file only
  28.  * under the terms of either the GPL or the LGPL, and not to allow others to
  29.  * use your version of this file under the terms of the MPL, indicate your
  30.  * decision by deleting the provisions above and replace them with the notice
  31.  * and other provisions required by the GPL or the LGPL. If you do not delete
  32.  * the provisions above, a recipient may use your version of this file under
  33.  * the terms of any one of the MPL, the GPL or the LGPL.
  34.  *
  35.  * ***** END LICENSE BLOCK ***** */
  36.  
  37. /*
  38.  * Header file for routines specific to S/MIME.  Keep things that are pure
  39.  * pkcs7 out of here; this is for S/MIME policy, S/MIME interoperability, etc.
  40.  *
  41.  * $Id: secmime.h,v 1.2 2004/04/25 15:03:13 gerv%gerv.net Exp $
  42.  */
  43.  
  44. #ifndef _SECMIME_H_
  45. #define _SECMIME_H_ 1
  46.  
  47. #include "secpkcs7.h"
  48.  
  49.  
  50. /************************************************************************/
  51. SEC_BEGIN_PROTOS
  52.  
  53. /*
  54.  * Initialize the local recording of the user S/MIME cipher preferences.
  55.  * This function is called once for each cipher, the order being
  56.  * important (first call records greatest preference, and so on).
  57.  * When finished, it is called with a "which" of CIPHER_FAMILID_MASK.
  58.  * If the function is called again after that, it is assumed that
  59.  * the preferences are being reset, and the old preferences are
  60.  * discarded.
  61.  *
  62.  * XXX This is for a particular user, and right now the storage is
  63.  * XXX local, static.  The preference should be stored elsewhere to allow
  64.  * XXX for multiple uses of one library?  How does SSL handle this;
  65.  * XXX it has something similar?
  66.  *
  67.  *  - The "which" values are defined in ciferfam.h (the SMIME_* values,
  68.  *    for example SMIME_DES_CBC_56).
  69.  *  - If "on" is non-zero then the named cipher is enabled, otherwise
  70.  *    it is disabled.  (It is not necessary to call the function for
  71.  *    ciphers that are disabled, however, as that is the default.)
  72.  *
  73.  * If the cipher preference is successfully recorded, SECSuccess
  74.  * is returned.  Otherwise SECFailure is returned.  The only errors
  75.  * are due to failure allocating memory or bad parameters/calls:
  76.  *    SEC_ERROR_XXX ("which" is not in the S/MIME cipher family)
  77.  *    SEC_ERROR_XXX (function is being called more times than there
  78.  *        are known/expected ciphers)
  79.  */
  80. extern SECStatus SECMIME_EnableCipher(long which, int on);
  81.  
  82. /*
  83.  * Initialize the local recording of the S/MIME policy.
  84.  * This function is called to enable/disable a particular cipher.
  85.  * (S/MIME encryption or decryption using a particular cipher is only
  86.  * allowed if that cipher is currently enabled.)  At startup, all S/MIME
  87.  * ciphers are disabled.  From that point, this function can be called
  88.  * to enable a cipher -- it is not necessary to call this to disable
  89.  * a cipher unless that cipher was previously, explicitly enabled via
  90.  * this function.
  91.  *
  92.  * XXX This is for a the current module, I think, so local, static storage
  93.  * XXX is okay.  Is that correct, or could multiple uses of the same
  94.  * XXX library expect to operate under different policies?
  95.  *
  96.  *  - The "which" values are defined in ciferfam.h (the SMIME_* values,
  97.  *    for example SMIME_DES_CBC_56).
  98.  *  - If "on" is non-zero then the named cipher is enabled, otherwise
  99.  *    it is disabled.
  100.  *
  101.  * If the cipher is successfully enabled/disabled, SECSuccess is
  102.  * returned.  Otherwise SECFailure is returned.  The only errors
  103.  * are due to bad parameters:
  104.  *    SEC_ERROR_XXX ("which" is not in the S/MIME cipher family)
  105.  *    SEC_ERROR_XXX ("which" exceeds expected maximum cipher; this is
  106.  *        really an internal error)
  107.  */
  108. extern SECStatus SECMIME_SetPolicy(long which, int on);
  109.  
  110. /*
  111.  * Does the current policy allow S/MIME decryption of this particular
  112.  * algorithm and keysize?
  113.  */
  114. extern PRBool SECMIME_DecryptionAllowed(SECAlgorithmID *algid, PK11SymKey *key);
  115.  
  116. /*
  117.  * Does the current policy allow *any* S/MIME encryption (or decryption)?
  118.  *
  119.  * This tells whether or not *any* S/MIME encryption can be done,
  120.  * according to policy.  Callers may use this to do nicer user interface
  121.  * (say, greying out a checkbox so a user does not even try to encrypt
  122.  * a message when they are not allowed to) or for any reason they want
  123.  * to check whether S/MIME encryption (or decryption, for that matter)
  124.  * may be done.
  125.  *
  126.  * It takes no arguments.  The return value is a simple boolean:
  127.  *   PR_TRUE means encryption (or decryption) is *possible*
  128.  *    (but may still fail due to other reasons, like because we cannot
  129.  *    find all the necessary certs, etc.; PR_TRUE is *not* a guarantee)
  130.  *   PR_FALSE means encryption (or decryption) is not permitted
  131.  *
  132.  * There are no errors from this routine.
  133.  */
  134. extern PRBool SECMIME_EncryptionPossible(void);
  135.  
  136. /*
  137.  * Start an S/MIME encrypting context.
  138.  *
  139.  * "scert" is the cert for the sender.  It will be checked for validity.
  140.  * "rcerts" are the certs for the recipients.  They will also be checked.
  141.  *
  142.  * "certdb" is the cert database to use for verifying the certs.
  143.  * It can be NULL if a default database is available (like in the client).
  144.  *
  145.  * This function already does all of the stuff specific to S/MIME protocol
  146.  * and local policy; the return value just needs to be passed to
  147.  * SEC_PKCS7Encode() or to SEC_PKCS7EncoderStart() to create the encoded data,
  148.  * and finally to SEC_PKCS7DestroyContentInfo().
  149.  *
  150.  * An error results in a return value of NULL and an error set.
  151.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  152.  */
  153. extern SEC_PKCS7ContentInfo *SECMIME_CreateEncrypted(CERTCertificate *scert,
  154.                              CERTCertificate **rcerts,
  155.                              CERTCertDBHandle *certdb,
  156.                              SECKEYGetPasswordKey pwfn,
  157.                              void *pwfn_arg);
  158.  
  159. /*
  160.  * Start an S/MIME signing context.
  161.  *
  162.  * "scert" is the cert that will be used to sign the data.  It will be
  163.  * checked for validity.
  164.  *
  165.  * "certdb" is the cert database to use for verifying the cert.
  166.  * It can be NULL if a default database is available (like in the client).
  167.  * 
  168.  * "digestalg" names the digest algorithm.  (It should be SEC_OID_SHA1;
  169.  * XXX There should be SECMIME functions for hashing, or the hashing should
  170.  * be built into this interface, which we would like because we would
  171.  * support more smartcards that way, and then this argument should go away.)
  172.  *
  173.  * "digest" is the actual digest of the data.  It must be provided in
  174.  * the case of detached data or NULL if the content will be included.
  175.  *
  176.  * This function already does all of the stuff specific to S/MIME protocol
  177.  * and local policy; the return value just needs to be passed to
  178.  * SEC_PKCS7Encode() or to SEC_PKCS7EncoderStart() to create the encoded data,
  179.  * and finally to SEC_PKCS7DestroyContentInfo().
  180.  *
  181.  * An error results in a return value of NULL and an error set.
  182.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  183.  */
  184. extern SEC_PKCS7ContentInfo *SECMIME_CreateSigned(CERTCertificate *scert,
  185.                           CERTCertificate *ecert,
  186.                           CERTCertDBHandle *certdb,
  187.                           SECOidTag digestalg,
  188.                           SECItem *digest,
  189.                           SECKEYGetPasswordKey pwfn,
  190.                           void *pwfn_arg);
  191.  
  192. /************************************************************************/
  193. SEC_END_PROTOS
  194.  
  195. #endif /* _SECMIME_H_ */
  196.